feat(clerk-js): Improve `getToken` offline handling #7598

bratsos · 2026-01-14T17:36:38Z

Description

offline-demo.mp4

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

Breaking Changes
- Major-version upgrades to Clerk packages; expect breaking changes.
- getToken() now throws ClerkOfflineError when offline instead of returning null — wrap calls in try/catch.
New Features
- New ClerkOfflineError class and type-guard (ClerkOfflineError.is) for detecting offline network failures.
Documentation
- Migration guide and examples for handling getToken() offline behavior and retry/offline UX.

changeset-bot · 2026-01-14T17:36:42Z

🦋 Changeset detected

Latest commit: dfa5223

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 21 packages

Name	Type
@clerk/tanstack-react-start	Major
@clerk/react-router	Major
@clerk/clerk-js	Major
@clerk/upgrade	Major
@clerk/nextjs	Major
@clerk/shared	Major
@clerk/react	Major
@clerk/nuxt	Major
@clerk/vue	Major
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/testing	Patch
@clerk/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-01-14T17:36:43Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 3, 2026 1:04pm

packages/clerk-js/src/core/resources/Base.ts

jacekradko · 2026-01-14T19:49:38Z

@bratsos I am concerned that this PR is going to conflict heavily with the stale-while-revalidate change: #7317

I think we will want to base this PR off feat/stale-while-revalidate-token and build on top of it. Some of the offline heuristics work well with SWR since we can return a cached token whenever possible and error only when we truly cannot fetch a new token

bratsos · 2026-01-28T21:25:05Z

.changeset/sparkly-aliens-see.md

+'@clerk/tanstack-react-start': major
+'@clerk/react-router': major
+'@clerk/clerk-js': major
+'@clerk/upgrade': major
+'@clerk/nextjs': major
+'@clerk/shared': major
+'@clerk/react': major
+'@clerk/nuxt': major
+'@clerk/vue': major


I'm not sure if this should be a major change in all sdks 🤔

I don't think so, but it doesn't really matter in practice as all of them are going to get a major anyways

Should I leave it like this then?

packages/clerk-js/src/core/resources/__tests__/Session.test.ts

jacekradko

Looks good overall. Just a couple of questions

BREAKING CHANGE: `getToken()` now throws `ClerkOfflineError` instead of returning `null` when the client is offline. This makes it explicit that the failure was due to network conditions, not authentication state.

…ffline

coderabbitai · 2026-02-02T21:18:28Z

📝 Walkthrough

Walkthrough

A new ClerkOfflineError class is added and re-exported from shared error modules. getToken() behavior changed: it now throws ClerkOfflineError when the client is offline instead of returning null. Session and core clerk logic were updated to catch and distinguish offline errors from other failures. Tests were added/updated to cover offline scenarios, and migration documentation describing the new try/catch usage was included.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main objective of the PR: improving offline error handling in getToken().
Linked Issues check	✅ Passed	The PR implements all three key requirements from USER-4063: prevents null return on offline, throws ClerkOfflineError to make offline explicit, and enables consumer-side offline handling.
Out of Scope Changes check	✅ Passed	All changes are focused on implementing offline error handling for getToken(). Error exports added to multiple packages are necessary for the new API to be accessible across the Clerk ecosystem.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Important

Action Needed: IP Allowlist Update

If your organization protects your Git platform with IP whitelisting, please add the new CodeRabbit IP address to your allowlist:

✨ 136.113.208.247/32 (new)
34.170.211.100/32
35.222.179.152/32

Failure to add the new IP will result in interrupted reviews.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2026-02-02T21:19:13Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7598

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7598

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7598

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7598

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7598

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7598

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7598

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7598

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7598

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7598

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7598

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7598

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7598

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7598

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7598

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7598

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7598

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7598

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7598

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7598

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7598

commit: dfa5223

…ne-handling

bratsos · 2026-02-03T13:05:16Z

!allow-major

vercel bot deployed to Preview January 14, 2026 17:36 View deployment

github-actions bot added clerk-js nextjs react tanstack astro react-router nuxt vue core-3 labels Jan 14, 2026

bratsos changed the base branch from main to alexbratsos/user-4045-make-gettoken-callable-outside-of-react January 14, 2026 17:37

jacekradko reviewed Jan 14, 2026

View reviewed changes

packages/clerk-js/src/core/resources/Base.ts Outdated Show resolved Hide resolved

Base automatically changed from alexbratsos/user-4045-make-gettoken-callable-outside-of-react to main January 16, 2026 16:45

bratsos force-pushed the alexbratsos/user-4063-improve-gettoken-offline-handling branch from b6350c6 to 640e362 Compare January 28, 2026 21:14

vercel bot deployed to Preview January 28, 2026 21:14 View deployment

bratsos changed the title ~~[WIP] feat(clerk-js): Improve getToken offline handling~~ feat(clerk-js): Improve getToken offline handling Jan 28, 2026

bratsos requested a review from jacekradko January 28, 2026 21:15

bratsos changed the base branch from main to feat/stale-while-revalidate-token January 28, 2026 21:16

bratsos marked this pull request as ready for review January 28, 2026 21:16

bratsos commented Jan 28, 2026

View reviewed changes

vercel bot deployed to Preview January 28, 2026 21:25 View deployment

Base automatically changed from feat/stale-while-revalidate-token to main January 30, 2026 02:56

bratsos force-pushed the alexbratsos/user-4063-improve-gettoken-offline-handling branch from 9de4869 to c647c6a Compare February 2, 2026 19:00

vercel bot deployed to Preview February 2, 2026 19:01 View deployment

jacekradko reviewed Feb 2, 2026

View reviewed changes

packages/clerk-js/src/core/resources/__tests__/Session.test.ts Outdated Show resolved Hide resolved

jacekradko approved these changes Feb 2, 2026

View reviewed changes

feat(clerk-js): Throw ClerkOfflineError from getToken() when offline

17c819a

BREAKING CHANGE: `getToken()` now throws `ClerkOfflineError` instead of returning `null` when the client is offline. This makes it explicit that the failure was due to network conditions, not authentication state.

bratsos added 2 commits February 2, 2026 22:15

chore: add changeset

a78a035

fixup! feat(clerk-js): Throw ClerkOfflineError from getToken() when o…

a36112f

…ffline

bratsos force-pushed the alexbratsos/user-4063-improve-gettoken-offline-handling branch from c04b2a4 to a36112f Compare February 2, 2026 21:16

vercel bot deployed to Preview February 2, 2026 21:16 View deployment

bratsos closed this Feb 2, 2026

bratsos reopened this Feb 2, 2026

Merge branch 'main' into alexbratsos/user-4063-improve-gettoken-offli…

dfa5223

…ne-handling

vercel bot deployed to Preview February 3, 2026 13:04 View deployment

bratsos merged commit 86d2199 into main Feb 3, 2026
87 of 92 checks passed

bratsos deleted the alexbratsos/user-4063-improve-gettoken-offline-handling branch February 3, 2026 14:02

nikosdouvlis pushed a commit that referenced this pull request Feb 12, 2026

feat(clerk-js): Improve getToken offline handling (#7598)

fb8519a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(clerk-js): Improve `getToken` offline handling #7598

feat(clerk-js): Improve `getToken` offline handling #7598

Uh oh!

bratsos commented Jan 14, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

jacekradko commented Jan 14, 2026

Uh oh!

bratsos Jan 28, 2026

Uh oh!

jacekradko Feb 2, 2026

Uh oh!

bratsos Feb 2, 2026

Uh oh!

Uh oh!

jacekradko left a comment

Uh oh!

coderabbitai bot commented Feb 2, 2026 •

edited

Loading

Walkthrough

Uh oh!

pkg-pr-new bot commented Feb 2, 2026 •

edited

Loading

Uh oh!

bratsos commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(clerk-js): Improve getToken offline handling #7598

feat(clerk-js): Improve getToken offline handling #7598

Uh oh!

Conversation

bratsos commented Jan 14, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jacekradko commented Jan 14, 2026

Uh oh!

bratsos Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

jacekradko Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

bratsos Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jacekradko left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

pkg-pr-new bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bratsos commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(clerk-js): Improve `getToken` offline handling #7598

feat(clerk-js): Improve `getToken` offline handling #7598

bratsos commented Jan 14, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 14, 2026 •

edited

Loading

vercel bot commented Jan 14, 2026 •

edited

Loading

coderabbitai bot commented Feb 2, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 2, 2026 •

edited

Loading